Click here to return to the VHDL Reference Guide. (last edit: 24. september 2012)

Textio

TEXTIO is a VHDL package which allows the reading and writing of ASCII text files from VHDL. TEXTIO is part of the IEEE 1076 standard, and is in the library STD. VHDL Source Of Package package TEXTIO is -- Type definitions for Text I/O type LINE is access STRING; -- a LINE is a pointer to a STRING value type TEXT is file of STRING; -- a file of variable-length ASCII records type SIDE is (RIGHT, LEFT); -- for justifying output data within fields subtype WIDTH is NATURAL; -- for specifying widths of output fields -- Standard Text Files (VHDL'87 version is similar) file INPUT: TEXT open READ_MODE is "STD_INPUT"; file OUTPUT: TEXT open WRITE_MODE is "STD_OUTPUT"; -- Input Routines for Standard Types procedure READLINE (variable f: in TEXT; L: inout LINE); procedure READ (L: inout LINE; VALUE: out BIT; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out BIT); procedure READ (L: inout LINE; VALUE: out BIT_VECTOR; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out BIT_VECTOR); procedure READ (L: inout LINE; VALUE: out BOOLEAN; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out CHARACTER; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out CHARACTER); procedure READ (L: inout LINE; VALUE: out INTEGER; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out INTEGER); procedure READ (L: inout LINE; VALUE: out REAL; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out REAL); procedure READ (L: inout LINE; VALUE: out STRING; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out STRING); procedure READ (L: inout LINE; VALUE: out TIME; GOOD: out BOOLEAN); procedure READ (L: inout LINE; VALUE: out TIME); -- Output Routines for Standard Types procedure WRITELINE (F: out TEXT; L: inout LINE); procedure WRITE (L: inout LINE; VALUE : in BIT; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in BIT_VECTOR; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in BOOLEAN; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in CHARACTER; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in INTEGER; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in REAL; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0; DIGITS: in NATURAL := 0); procedure WRITE (L: inout LINE; VALUE: in STRING; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0); procedure WRITE (L: inout LINE; VALUE: in TIME; JUSTIFIED: in SIDE := RIGHT; FIELD: in WIDTH := 0; UNIT: in TIME := ns); -- function ENDFILE(F: in TEXT) return BOOLEAN; -- ENDFILE is implicitly declared for all file types end TEXTIO;

Rules

READ skips leading white space except when reading types CHARACTER and STRING. The FIELD parameter to WRITE gives the minimum field width.

Things to remember

The READ and WRITE procedures are only defined for types in package STANDARD, not for user defined types. The function ENDLINE (as defined in the VHDL'87 standard) is not legal VHDL, so cannot be used! To WRITE a text string, a qualified expression must be used, e.g. WRITE (L, STRING'("Hello World!"));

Tips

For a line that is being read, L'LENGTH = 0 when the end of the line has been reached. In VHDL'95, the attributes 'IMAGE and 'VALUE are useful for writing and reading non-standard data types.

Example

  -- Writing a text file
  signal A, B, G: Bit_vector(3 downto 0);
  ...
  Monitor: process
    use STD.TEXTIO.all;
    file F: TEXT is out "test.txt";             --VHDL'87
    file F: TEXT open WRITE_MODE is "test.txt";
    variable L: LINE;
  begin
    -- Strobe the signals...
    wait until Rising_edge(Clock);
    wait for Settling_time;

    WRITE (L, NOW, Left, 10); -- NOW = current simulation time
    WRITE (L, A,   Right, 5);
    WRITE (L, B,   Right, 5);
    WRITE (L, G,   Right, 5);

    WRITELINE (F, L);
  end process;

  -- Reading a text file
  signal A, B: BIT_VECTOR(3 downto 0);
  ...
  Stimulus: process
    use STD.TEXTIO.all;
    file F: TEXT is in "vectors.txt";            --VHDL'87
    file F: TEXT open READ_MODE is "vectors.txt";
    variable L: LINE;
    variable TimeWhen: TIME;
    variable Avalue, Bvalue: BIT_VECTOR(3 downto 0);
  begin
    while not ENDFILE(F) loop
      READLINE (F, L);
      READ (L, TimeWhen);
      READ (L, Avalue);
      READ (L, Bvalue);
      wait for TimeWhen-NOW; -- Wait until an absolute time
      A <= Avalue;
      B <= Bvalue;
    end loop;
    wait;
  end process;

See Also

File, Report, Standard, Attribute Name